﻿// --------------------------------------------------------------------------------------------------------------------
// <copyright file="ICacheProvider.cs" company="XamlNinja">
//   2011 Richard Griffin and Ollie Riches
// </copyright>
// <summary>
//   Interface for WP7 caching providers - all providers should support expiring of caching items, all data add must be a reference type.
// </summary>
// --------------------------------------------------------------------------------------------------------------------

namespace WP7Contrib.Caching
{
    using System;
    using System.Collections;
    using System.Collections.Generic;

    /// <summary>
    /// Interface for WP7 caching providers - all providers should support expiring of caching items, all data add must be a reference type.
    /// </summary>
    public interface ICacheProvider
    {
        /// <summary>
        /// Add a value to the cache with a relative expiry time, e.g 10 minutes.
        /// </summary>
        /// <typeparam name="TKey">
        /// The type of the key.
        /// </typeparam>
        /// <typeparam name="TValue">
        /// The type of the value.
        /// </typeparam>
        /// <param name="key">
        /// The key value.
        /// </param>
        /// <param name="value">
        /// The value, can be null.
        /// </param>
        /// <param name="relativeTime">
        /// The relative date time when the key value pair should expire and be purged from the cache.
        /// </param>
        void Add<TKey, TValue>(TKey key, TValue value, TimeSpan relativeTime) where TValue : class;

        /// <summary>
        /// Add a value to the cache with an absolute time, e.g. 01/01/2020.
        /// </summary>
        /// <typeparam name="TKey">
        /// The type of the key.
        /// </typeparam>
        /// <typeparam name="TValue">
        /// The type of the value.
        /// </typeparam>
        /// <param name="key">
        /// The key value.
        /// </param>
        /// <param name="value">
        /// The value, can be null.
        /// </param>
        /// <param name="absoluteTime">
        /// The absolute date time when the cache should expire and be purged the value.
        /// </param>
        void Add<TKey, TValue>(TKey key, TValue value, DateTime absoluteTime) where TValue : class;

        /// <summary>
        /// Gets a value from the cache.
        /// </summary>
        /// <typeparam name="TKey">
        /// The type of the key.
        /// </typeparam>
        /// <typeparam name="TValue">
        /// The type of the value.
        /// </typeparam>
        /// <param name="key">
        /// The key associated with value.
        /// </param>
        /// <returns>
        /// If the key exists in the cache then the value is returned, if the key does not exist then null is returned.
        /// </returns>
        TValue Get<TKey, TValue>(TKey key) where TValue : class;

        /// <summary>
        /// Remove a value from the cache.
        /// </summary>
        /// <param name="key">
        /// The key associated with the value.
        /// </param>
        /// <typeparam name="TKey">
        /// The type of the key.
        /// </typeparam>
        void Remove<TKey>(TKey key);

        /// <summary>
        /// Clears the contents of the cache.
        /// </summary>
        void Clear();

        /// <summary>
        /// Allows an initialisation required for the cache provider to be executed at the user request
        /// </summary>
        void PreemptiveInitialise();

        /// <summary>
        /// Returns true if the value can be cached - we use this during unit tesing to confirm classes you want to cache can be cached with the
        /// specific implementation.
        /// </summary>
        /// <typeparam name="T">The type of the value.</typeparam>
        /// <param name="value">The value to checkd for cachability.</param>
        /// <param name="failingTypes">The types failing </param>
        /// <returns>Returns true if the value can be added to the cache.</returns>
        bool IsCacheable<T>(T value, ref IEnumerable<Type> failingTypes) where T : class;

        /// <summary>
        /// Gets an enumerator for keys of a specific type.
        /// </summary>
        /// <typeparam name="TKey">The type of the key.</typeparam>
        /// <returns>Returns an enumerator for keys of a specific type.</returns>
        IEnumerable<TKey> Keys<TKey>();
    }
}